\hfil \vskip 1in \centerline{\chapfont DVIDIS v3.4 \bigskip \centerline{Documentation Version of 6-Apr-88 \vskip 1in |DVIDIS| is a program that displays \TeX{ |DVI| files on a VaxStation running VWS. \litem{0in{\bf NOTE{5pcIf you have used previous versions of |DVIDIS|, note that this version is VERY different. The human interface is much better, but most important, the program now reads |PK| format font files, not the old, very obsolete |RST| format font files. It is possible to build a version with |RST| file support, but that hasn’t been tested and is not recommended. |PK| fonts are MUCH better in every way. \parindent 0pt Basic usage is very simple. To display file |TEXT.DVI|, for example, just type: \begintt $ DVIDIS TEXT \endtt on your VAXStation. A large window will be created, and your text should start to appear in it; depending on the paper size and where you have located your window (by default it starts out centered), you may be able to see the “edge” of the paper as a gray bar. Meanwhile, your keyboard will remain attached to the window you were previously in, and you can enter commands. For a list of commands available to you, hit the |HELP| key. The effect of the various commands is easy to see, so experiment until you feel comfortable with them. You can also specify a couple of options on the |DVIDIS| command line. These CANNOT be changed once |DVIDIS| has started. All options are of the form “|-l|” where “|l|” is any single letter, with the single exception of |-verbose| (for historical reasons). Some are followed — after a space — by one or a pair of numeric arguments; the |-s| command must be followed by a paper size specification. For example: \begintt $ DVIDIS -w -p 2 4 TEXT \endtt means “display pages 2 to 4 of |TEXT.DVI| in ’Wide’ mode”. The following options are commonly used: \litem{0pt{|-c|{5pcThe fonts that |DVIDIS| uses are meant for a 300 dpi printer. A VAXStation display has about 78 dpi. As a result, if you display the glyphs from these fonts at a 1–1 pixel-to-pixel mapping, they are about 4 times as large as they would be on the page, and only about 1/9 of the page is visible at a time. Normally, |DVIDIS| compresses all fonts by a 2-to-1 factor. The fonts are still readable, but you can now get most of the width of a page — all, with any reasonable margins — and half the height on the screen. Specifying “|-c|” turns off this compression; it’s useful mainly for looking at the glyphs, not the text. \litem{0pt{|-w|{5pcSpecifies a 4-to-1 glyph compression factor. This allows you to see how a whole page looks, but unfortunately it’s rather hard to read the resulting text. \litem{0pt{|-m|{5pcTells |DVIDIS| to try to use smaller fonts, rather than compressing larger ones. This only works if you actually HAVE the small fonts on your system. When it works, it improves the appearance of individual characters, although it often makes lines come out with slightly different lengths than they should. |-m| is especially useful in conjunction with |-w|. |-m| in conjunction with |-c| is meaningless. \litem{0pt{|-s ss|{5pc{Set the paper size. This determines what size paper the program assumes you are printing on. The default is “letter”, which is 8.5 x 11 inches. The argument is the name of a paper size; type |DVIDIS -s ?| for a list of possible values. \hang The paper size controls where |DVIDIS| places a visible gray border, and when it tells you that characters have “run off the page”. It always displays the characters, however. \hang Paper size “|huge|” is meant for special purposes; using it will make many of the commands you can type to |DVIDIS| while it is running work in strange ways. You should generally avoid using size “|huge|”. \litem{0pt{|-verbose|{5pcMakes the program talkative. This is mainly useful for debugging, but since it displays all the font files it opens, successfully or not, it can be used to determine which files are needed. The needed files can be created if they don’t already exist. They can also be put on your workstation’s local disk to improve performance. \parindent 0pt The rest of the options are rarely used: \litem{0pt{|-v <mi>, -h <mi>|{8pc{Set the vertical (horizonal) margin. Next argument is the margin, in milli-inches. Default is 1000 milli-inches each, which is the same default used by many common |DVI| printing programs. If you find a lot of “off-screen glyph” errors, and you have the paper size set correctly, try changing these parameters. (Besides 1000, the second most common value expected is 0 for both margins.) Note that the default corresponds to the current \TeX{ standard. If you find you have to use some other value to make your output look right, some other piece of software you are running is obsolete. \litem{0pt{|-p <s> <e>|{8pcLimits the display to pages |<s>| through |<e>| inclusive. You can only specify one page range at a time, but you can specify multiple |-p| options, each specifying a page range. When you specify page ranges, |DVIDIS| will only “see” pages within the ranges given. Nothing you can do while the program is running will let you display any page not within any page range — |DVIDIS| will simply skip past the pages. \litem{0pt{|-f|{8pcCauses the program to look in “|USER$RST|” rather than “|TEX$RST|” for the fonts. This command is meaningless for the |PK| version of |DVIDIS|, and of little use even in the |RST| version. \litem{0pt{|-d|{8pcDebug. Generates a lot of output that’s useful only to developers. \parindent 0pt \bigskip {\secfont PROGRAM INSTALLATION |DVIDIS| consists of a single image, |DVIDIS.EXE|, that runs on an VAXStation with VWS V3.0 or later. It runs as a normal user-mode image, and needs no special privileges. |DVIDIS| uses a fair amount of memory as it runs, so be sure to provide a reasonable working set — at least 1200 pages, 2000 or more is better. In order for |DVIDIS| to receive its arguments, it must be started with a foreign command line, given by something like: \begintt $ DVIDIS :== $DEV:[DIR]DVIDIS \endtt Two “environment variables” can be set to control |DVIDIS|, and you can specify font substitutions. The environment variables — typically, logicals, but if no logicals are defined any |DCL| symbol of the same name will be used — \litem{0in{|DVIDIS\_FILE\_FORMAT|{9pcA string that specifies how to construct a file specification for a font file, given a font name and a dots-per-inch value. The font name will be substituted for |%s|; the dots-per-inch value for |%d|. You must have EXACTLY one of each, in either order; you may NOT have any additional occurences of “|%|”. There are two common schemes for storing |PK| font files: \litem{9pc{$\bullet${10pcOne directory, |DEV:[DIR]|, font “|name|” at “|ddd|” dots per inch is file |name.dddPK|. A format string for this case would look like \hfil\break “|DEV:[DIR]%s.%dPK|”. \litem{9pc{$\bullet${10pcOne root directory, |DEV:[DIR.]|; fonts at “ddd” dots per inch are in subdirectory |[.DPIddd]|, with font “name” in |name.PK|. A format string for this case would look like “|DEV:[DIR.DPI%d]%s.PK|”. \parindent9pc\hangindent\parindent \hang If |DVIDIS_FILE_FORMAT| is not defined, the default format string is \hfil\break “|TEX_FONTS:[DPI%d]%s.PK|”. This corresponds to the second way of organizing the font files, and assumes that |TEX_FONTS| is a rooted logical translating to something like |DEV:[DIR.]|. \hang You can only specify a single file format, but that file format could involve a logical that translates to a search list. For example, using the default file format, you might do: \hang | $ DEFINE TEX_FONTS $DISK1:[TEX.PK.],NODE::TEX_FONTS:| \hang where “|NODE|” is the name of a node with more fonts than you are willing to store locally. On |NODE|, |TEX_FONTS| must be a SYSTEM logical name that translates to a rooted directory. (If you have proxy access to |NODE|, you could define |TEX_FONTS| in your login file on |NODE|). Because of a VMS bug, it isn’t possible to use something like |NODE::DEV:[DIR.]| to avoid needing a logical name on NODE. (This bug appears in VMS Version 4.5. If you a more recent version, the bug may have been fixed.) \hang IMPORTANT NOTE \hang The definition of |DVIDIS_FILE_FORMAT| will be used as a |printf()| format string. The “|d|” and “|s|” format specifiers MUST be in lower case; if you make them upper case, the format will not work. Note also that |DCL| forces characters to upper case unless they are inside a quoted string. Hence, your definition should look something like: \hang | $ DEFINE DVIDIS_FILE_FORMAT “TEX_FONTS:%s.%dPK”| \litem{0pt{|DVIDIS\_FONT\_SIZES|{9pcThis variable must translate to a list of all dot-per-inch values at which you have any fonts available. The list consist of just the numbers (the “|ddd|” values discussed above), separated by commas. |DVIDIS| will never find a font at a size not given in the list. \hang The default list is: \hang |100,121,145,174,180,208,210,225,240,250,263,270,274,|\hfil\break |300,329,360,432,518,622,746,895,896,1074,1075,1289,|\hfil\break |1290,1547,1548| \hang which is the list of values I’ve got. Extra values will slow |DVIDIS| down a bit when it has to open a file, but not by much, so you can use the default unless you have some sizes I don’t. \hang Note that this list is NOT a search list, use: \hang | $ DEFINE DVIDIS_FONT_SIZES “300,329,360”| \hang WITH THE QUOTATION MARKS. If you leave the quotation marks off, |DVIDIS| will never use anything but the first value you list. \parindent 0pt \bigskip {\secfont FONT SUBSTITUTION If |DVIDIS| is unable to find a font as specified, it will check to see if you have defined a substitute for it in any of three substitution files. If you are displaying file |jobname.DVI|, the files are: \begintt jobname.SUB in the same directory as jobname.DVI; TEXFONTS.SUB in the current directory; TEX$INPUTS:TEXFONTS.SUB \endtt Every time a substitution is needed, the files present are checked, in the order given, each from beginning to end, to try to find a substitute. Only the first match is used, however. Each of the substitution files has the same format. It’s a simple ASCII file, with one substitution per line. Comments, as in \TeX, are introduced by “|%|” and continue to the end of the line. A substitution line has either of two forms: \begintt oldname.oldsize -> subname.subsize oldname -> subname \endtt The first format substitutes only for a particular font name and size. The second format substitutes for a particular font name at any size. Spaces can be used freely in substitution lines. Since only the first match is used, and the files are always read from the first line onward, you should specify particular substitutions — those with a size — before generic ones. It’s not an error for the substituted font file not to be found — |DVIDIS| will proceed to look for “nearby” fonts, possibly substituting for them as well. The |DVIDIS| distribution includes a |TEXFONTS.SUB| file that substitutes |CM| fonts for |AM| fonts. This should allow you to display |DVI| files created using older versions of \TeX. \bigskip {\secfont GETTING THE FIND AND REMOVE KEYPAD KEYS TO WORK The |Find| and |Remove| keypad keys use |OSC| functions to control the terminal window. |OSC|’s must be enabled; from questions I’ve received, it seems that many people are not enabling them. To enable |OSC|’s, issue the following command from |DCL| (in a privileged account): \begintt $ DEFINE/SYSTEM/EXEC UIS$VT_ENABLE_OSC_STRINGS TRUE \endtt \bigskip {\secfont KNOWN BUGS AND RESTRICTIONS |DVIDIS| is intended to report an error if it can’t find a “close” match to a font called for in the file it is displaying. The test it makes for “closeness” is wrong, however, so it currently almost never reports a problem. The result may be grossly distorted output, with no indication that the problem isn’t in the file, it’s that |DVIDIS| had to chose an inappropriate font. Characters actually appearing in the font file, but with no pixels (i.e., a “0 by 0” raster) cause |DVIDIS| to crash. This is known to occur with the |CMAPL10| font (at least character ’040 is a “space”) and probably will occur with any of the La\TeX{ “invisible” slide fonts. Stanford Version 2.2 of |PXTOPK|, and all distributed versions to date of Kellerman and Smith’s |PXTOPK| for VMS, have distinct bugs that produce completely invalid |PK| files. Files produced using the Stanford V2.2 code can be recognized by using |PKTYPE| and looking at the X-offset and Y-offset values for a couple of characters. Typical values are small positive or negative integers — values outside the range -30 to 30 are very unlikely. The V2.2 code will produce random, often very large, values. I don’t know the exact symptoms of the problems the Kellerman and Smith code will produce. See the article by Dan Hosek in \TeX hax, Volume 88, \#24 for a discussion. Version 2.3 of |PXTOPK| fixes the underlying problem; both |PXTOPK.WEB| and a corresponding version of |PXTOPK.VMS-CHANGES| should be available from “the usual sources”, or from the same place you got |DVIDIS|, if all else fails. |DVIDIS| uses the |dx| field of |PK| fonts to determine the width of the characters it displays. Width information can also be obtained from the “|TFM width|” field. It seems that most commonly-used |DVI| file drivers use the |TFM| width. As a result, bugs that result in |PK| files with invalid |dx| values can go undetected for years. The most common case, easily detectable with |PKTYPE|, will have |dx=0| for all the characters. When such a font is displayed, what you’ll see is bunches of characters displayed at the same position; since inter-word spacing doesn’t depend on the |dx| values, you’ll see one “blotch” per word. One place I’ve seen this come up is with the Hebrew fonts that come with Jacques Goldberg’s Semi\TeX. Examination of the |GF| files reveals that they have 0 |dx| values as well, so the problem seems to be some (as-yet undetermined) inappropriate parameter setting for |Metafont|. You can work around this problem by doing a round-about conversion: Rather than using |GFTOPK|, use |GFTOPX| (or |PKTOPX|, if you’ve already got |PK| files), then |PXTOPK|. |PX| files don’t store the dx value at all, so a CORRECT |PXTOPK| will re-compute If |DVIDIS_FONT_SIZES| specifies exactly one font size, unpredictable results, including crashes, may occur. This shouldn’t happen under normal circumstances, but if you find a distorted display and other odd things happening, it could be that |DVIDIS_FONT_SIZES| is set up wrong. In particular, make sure that you’ve defined it to have a single translation that contains a list of sizes separated by commas, rather than as multiple translations, each of which is a single size. This is discussed above. If the original \TeX{ run specified a magnification value other than 1000, the spacing will be incorrect. The only current work-around is to re-run \TeX{ without the magnification. Note that this restriction applies only to GLOBAL magnifications (i.e., uses of |\magification|). Individually magnified fonts are handled correctly. There is a bug in the VAX C library for Versions 4.6 and 4.7 of VMS that will cause |DVIDIS| to die with a Reserved Operand Fault if it runs out of memory. The only work-around is to increase the amount of virtual memory available to the process running |DVIDIS|. (Note that, without the bug, |DVIDIS| would try to recover by discarding some font information it has already read in. The resulting performance loss would probably be substantial, so you’d probably want to run with a larger virtual memory limit anyway. On a workstation, there is little reason NOT to run this way in any case. You’ll probably want to allow big working sets, too.) \litem{0in{Author:{4pcJerry Leichter, based on work of Bill Gropp’s, which in turn was based on a lot of earlier work by others; with additional input from Bert Beander at DEC. Comments/questions/suggestions to Jerry Leichter at \hang LEICHTER-JERRY@CS.YALE.EDU\hfil\break or\hfil\break LEICHTER@YALEVMS.BITNET

This document was generated on November 19, 2022 using texi2html 5.0.